There are two values associated with every string variable in Blazin' Forth. The first is the maximum allowable length of the string, which is set when you create a string variable. The second is the actual length of the string, which is set when you actually store the string in the variable. It is important to keep this in mind when using strings, since the string operators will truncate the string if you try to store more characters in the string than you have allotted room for. Of course, you don't have to use the whole space, but you can't overflow it.
STRING STRINGS
These two words are used to reserve variable space for the strings in memory. STRING is used to allocate a single string variable, while STRINGS allocates a string array. You must always tell Forth how long your string is going to be. It can be any length, within the maximum limit of 255. Example:
10 STRING NAME$
Creates a string variable called NAME$ in the dictionary. Space is reserved for 10 characters. This variable will behave exactly like a regulation Forth variable, and leave its address on the stack. Note that the address is the address of the count byte, which allows you to use COUNT TYPE on the string to type it out.
STRINGS requires the number of strings you intend to store, as well as their maximum length. Example:
5 20 STRINGS ARRAY$
Reserves room in the dictionary for 5 strings of 20 characters each. To access the 3rd string in ARRAY$, you simply type:
*fp0
3 ARRAY$
And the address of the third 20 character string in ARRAY$ will be left on the stack. Each string in a string array is stored with its own count byte, and the address left when you access a string in a string array will be the address of the length byte for that string. Note that both STRING and STRINGS initialize the string length to zero.
"
" is used to compile string literals. When it is executed, it leaves the address of the count byte of the string on the stack. For example:
: JOHN$ " JOHN" COUNT TYPE ;
When executed, JOHN$ will print JOHN on the terminal. Note that " may also be used outside a definition. In this case, the string will be stored at PAD, and the current address of PAD will be left on the stack.
$SIZE $LENGTH
These two words are used to determine the length of strings or their maximum allowable size. $SIZE will leave the maximum allowable length of the string on the stack, while $LENGTH will leave the length of the string currently stored in the variable. Example:
NAME$ $SIZE ( leaves the maximum number of characters allowable in NAME$)
NAME$ $LENGTH ( leaves the length of the string currently stored in NAME$)
$!
This word is used to store a string in a variable. You can use it to initialize a string variable from a string literal. Example:
" This is a string" NAME$ $! ( store string literal in NAME$)
Note that strings will be truncated to the max length allowable for the string variable you are moving the string too. So for example, if NAME$ was created with a maximum size of 5, the only characters actually stored in NAME$ would be "THIS ".
You can also move strings from one variable to another with this word:
TRASH$ NAME$ $! ( move the string in TRASH$ to NAME$ )
Note that this word only operates on string variables - you can't use it, for example, to move a string to the PAD (see COPY$ for a way to do this.)
$+
This performs the concatenation operation. Once again, if the total length of the concatenated string exceeds the length of the variable, then the string will be truncated. Example:
FOO$ BAR$ $+ ( the concatenated string is left in FOO$ )
Strings may be added (concatenated) to themselves:
FOO$ FOO$ $+ or FOO$ DUP $+
$?
This simply types out the string. Example:
NAME$ $? ( type current string in NAME$)
COPY$
This word will extract a portion of a string, and move it to another string. It takes four arguments. The string address from which the string is going to be copied, the starting character of the substring, then ending character of the substring, and the destination. Example:
NAME$ 2 4 LIST$ COPY$ ( move characters 2 thru 4 of NAME$ to the start of LIST$)
You can also move a string to the pad with this word:
NAME$ 2 10 PAD COPY$ ( move characters 2-10 of NAME$ to the PAD)
Note that you can move the entire string by simply giving indexes of 1 and 255:
NAME$ 1 255 PAD COPY$ ( move the whole string to the PAD)
+$!
This word is used to store a string in the middle of another string. For example:
NAME$ JUNK$ 4 +$!
Will store NAME$ starting at the 4th character in JUNK$. This is a very useful string operation, particularly in conjuntion with COPY$ :
NAME$ 2 4 PAD COPY$ PAD JUNK$ 4 +$!
Will move the 2 thru the 4th characters of NAME$ to JUNK$, starting at the 4th character of JUNK$ ( try this one in BASIC!).
Note that +$! will only modify an already initialized string. For example, if JUNK$ contains a 10 character string, then:
NAME$ 2 4 PAD COPY$ PAD JUNK$ 11 +$!
will be a null operation. There are often cases when you want to build up an unitialized string from smaller pieces, or to use a single string variable as a one dimensional string array. To do this, you must first initialize the string to all spaces. The word $BLANK has been provided for this purpose. $BLANK will set the entire string to spaces, and then set the length of the string equal to the maximum size for that string. Example:
LIST$ $BLANK ( blank LIST$)
IN$
This word will find the first occurence of a string in another string, and return the index of the first character. If nothing is found, a 0 is returned. Example:
NAME$ LIST$ IN$ ( return the first occurence of NAME$ in LIST$)
$= $< $> $<> $<= $>=
These are the string boolean operators. Note that, everything else being equal, the longer string is considered the greater, and also that lower case is not the same as upper case.
>LOWER
This word is principly useful for carrying out string comparisons when you want to ignore case. It takes a starting address, and a count, and converts the entire thing to lower case. (Lower case being the same as upper case when the computer is in uppercase/graphics mode). Note that the string is converted where it stands, so if you want to preserve the original form, move it somewhere else before using this word.
Example: Check if two strings are equal:
NAME$ TEST$ $=
Example: Check if two strings are equal, but ignore case:
NAME$ DUP COUNT >LOWER TEST$ DUP COUNT >LOWER $=
Example: Check if two strings are equal, ignore case, but preserve the original form of the strings:
NAME$ 1 255 PAD COPY$ ( move to pad)
PAD COUNT >LOWER ( convert to lower case)
TEST$ TRASH$ $! ( move TEST$ to a temporary variable)
TRASH$ COUNT >LOWER ( convert to lower case)
PAD TRASH$ $= ( compare)
INPUT$
This accepts input from the keyboard, and moves the string to the variable whose address is on the stack. Note that the PAD is used for temporary storage, and a copy will remain there immediately after using this word. Note also that the full length of the input will be in pad, but it will be truncated if moved to a variable which is not large enough.
Example:
: GETNAME ." Please type your name " NAME$ INPUT$ ;
This example will prompt the user, and store his response in NAME$.
VALUE$
This word will convert a string stored at an address to a double number on the stack. Example:
NUMBER$ VALUE$ ( convert the string in NUMBER$ to a double number on the stack.)
Using these basic string operations, all necessary string handling operations may be carried out. You can also easily define your own custom string handling words. For example, if you are particularly fond of BASIC's string handling procedures, it is easy to define Forth equivalents using these operators. For example:
: LEFT$ ( addr1 n addr2 --)
>R 1 SWAP R> COPY$ ( move n leftmost characters of addr1 to addr2) ;
Which you would use as follows:
NAME$ 4 TEMP$ LEFT$ ( the 4 leftmost characters in NAME$ are left in TEMP$)
: RIGHT$ ( Move n right most characters of addr1 to addr2.
Stack: addr1 n addr2 -- )
>R OVER $LENGTH 1+ SWAP - OVER $LENGTH R> COPY$ ;
You would use RIGHT$ as follows:
NAME$ 4 TEMP$ RIGHT$ ( the 4 rightmost characters of NAME$ are left in TEMP$.)
You can use definitions like these to easily convert BASIC programs to FORTH. Personally, I think you will find it more flexible in the long run to use indexes into the strings, rather than the less flexible BASIC type of command. That's only an opinion - many people have lived long and productive lives, and never once indexed into a string.
